---
title: CSS & 스타일링
description: 맞춤형 CSS로 Starlight 사이트의 스타일을 지정하거나 Tailwind CSS와 통합하는 방법을 알아보세요.
---

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

사용자 정의 CSS 파일을 사용하여 Starlight 사이트의 스타일을 지정하거나 Starlight Tailwind 플러그인을 사용할 수 있습니다.

사이트의 기본 스타일을 빠르게 변경하려면 [커뮤니티 테마](/ko/resources/themes/)를 확인하세요.

## 사용자 정의 CSS 스타일

Starlight의 기본 스타일을 수정하거나 확장하기 위한 CSS 파일을 제공하여 사이트에 적용된 스타일을 원하는대로 변경할 수 있습니다.

<Steps>

1. `src/` 디렉터리에 CSS 파일을 추가합니다. 예를 들어, 아래 코드를 통해 페이지 제목을 더 넓게 만들고, 더 큰 텍스트를 사용할 수 있습니다.

   ```css
   /* src/styles/custom.css */
   :root {
   	--sl-content-width: 50rem;
   	--sl-text-5xl: 3.5rem;
   }
   ```

2. `astro.config.mjs` 파일에 있는 Starlight의 `customCss` 배열에 CSS 파일 경로를 추가하세요.

   ```diff lang="js"
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: '사용자 정의 CSS를 사용한 문서',
   			customCss: [
   +				// 사용자 정의 CSS 파일의 상대 경로
   +				'./src/styles/custom.css',
   			],
   		}),
   	],
   });
   ```

</Steps>

사이트를 스타일링하기 위해 Starlight에서 사용되는 모든 CSS 속성을 [`props.css` 파일](https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css)에서 확인할 수 있습니다.

### 캐스케이드 레이어

Starlight는 스타일 순서를 관리하기 위해 내부적으로 [캐스케이드 레이어](https://developer.mozilla.org/ko/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)를 사용합니다. 이를 통해 예측 가능한 CSS 순서를 보장하고 더 간단한 재정의를 할 수 있습니다.
레이어가 지정되지 않은 사용자 정의 CSS는 기본 Starlight 스타일을 재정의합니다.

캐스케이드 레이어를 사용하고 있다면, 사용자 정의 CSS에서 [`@layer`](https://developer.mozilla.org/ko/docs/Web/CSS/@layer)를 사용하여 `starlight` 레이어의 스타일을 기준으로 서로 다른 레이어의 우선순위를 정의할 수 있습니다.

```css "starlight"
/* src/styles/custom.css */
@layer my-reset, starlight, my-overrides;
```

위 예시는 `my-reset`이라는 사용자 정의 레이어를 정의하며, 이는 모든 Starlight 레이어보다 먼저 적용됩니다. 또 다른 레이어인 `my-overrides`는 모든 Starlight 레이어 이후에 적용됩니다. `my-overrides` 레이어의 모든 스타일은 Starlight의 스타일보다 우선 적용되지만, Starlight는 여전히 `my-reset` 레이어에 설정된 스타일을 변경할 수 있습니다.

## Tailwind CSS

Astro 프로젝트의 Tailwind CSS v4 지원은 [Tailwind Vite 플러그인](https://tailwindcss.com/docs/installation/using-vite)을 통해 제공됩니다.
Starlight는 Starlight 스타일과 호환되도록 Tailwind를 구성하는 데 도움이 되는 보완 CSS를 제공합니다.

Starlight Tailwind CSS는 다음 구성을 적용합니다.

- Starlight의 다크 모드와 작동하도록 Tailwind의 `dark:` 변형을 구성합니다.
- Starlight UI에서 Tailwind [테마 색상 및 글꼴](#tailwind로-starlight-스타일링하기)을 사용합니다.
- Tailwind Preflight 리셋 스타일의 필수적인 부분을 복원합니다.

### Tailwind가 포함된 새 프로젝트 만들기

`create astro`를 사용하여 Tailwind CSS가 사전 구성된 새 Starlight 프로젝트를 시작하세요.

<Tabs syncKey="pkg">
<TabItem label="npm">

```sh
npm create astro@latest -- --template starlight/tailwind
```

</TabItem>
<TabItem label="pnpm">

```sh
pnpm create astro --template starlight/tailwind
```

</TabItem>
<TabItem label="Yarn">

```sh
yarn create astro --template starlight/tailwind
```

</TabItem>
</Tabs>

### 기존 프로젝트에 Tailwind 추가하기

이미 Starlight 사이트가 존재할때, Tailwind CSS를 추가하려면 다음 단계를 따르세요.

<Steps>

1. 다음 명령을 실행하고 터미널의 지침에 따라 프로젝트에 Tailwind를 설정합니다.

   <Tabs syncKey="pkg">

   <TabItem label="npm">

   ```sh
   npx astro add tailwind
   ```

   </TabItem>

   <TabItem label="pnpm">

   ```sh
   pnpm astro add tailwind
   ```

   </TabItem>

   <TabItem label="Yarn">

   ```sh
   yarn astro add tailwind
   ```

   </TabItem>

   </Tabs>

2. Starlight의 Tailwind 호환성 패키지를 설치합니다.

   <Tabs syncKey="pkg">

   <TabItem label="npm">

   ```sh
   npm install @astrojs/starlight-tailwind
   ```

   </TabItem>

   <TabItem label="pnpm">

   ```sh
   pnpm add @astrojs/starlight-tailwind
   ```

   </TabItem>

   <TabItem label="Yarn">

   ```sh
   yarn add @astrojs/starlight-tailwind
   ```

   </TabItem>

   </Tabs>

3. Astro가 스캐폴딩한 `src/styles/global.css` 파일의 콘텐츠를 Starlight와의 호환성을 위해 다음 코드로 교체합니다.

   ```css
   /* src/styles/global.css */
   @layer base, starlight, theme, components, utilities;

   @import '@astrojs/starlight-tailwind';
   @import 'tailwindcss/theme.css' layer(theme);
   @import 'tailwindcss/utilities.css' layer(utilities);
   ```

   이 Tailwind 테마 구성은 Starlight의 [캐스케이드 레이어](#캐스케이드-레이어) 순서를 정의하고, Starlight의 Tailwind 보완 CSS와 Tailwind 테마, 유틸리티 스타일을 가져옵니다. 프로젝트에 추가 Tailwind 구성이 필요한 경우 ["여러 Tailwind 구성 사용하기"](#여러-tailwind-구성-사용하기) 섹션을 확인하세요.

4. `customCss` 배열의 첫 번째 항목으로 Tailwind CSS 파일을 추가하도록 Starlight 구성을 업데이트합니다.

   ```js ins={11-12}
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import tailwindcss from '@tailwindcss/vite';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: 'Tailwind를 사용한 문서',
   			customCss: [
   				// Tailwind 기본 스타일의 경로입니다.
   				'./src/styles/global.css',
   			],
   		}),
   	],
   	vite: { plugins: [tailwindcss()] },
   });
   ```

</Steps>

### Tailwind로 Starlight 스타일링하기

[Tailwind를 사용하여 새 Starlight 프로젝트를 만들거나](#tailwind가-포함된-새-프로젝트-만들기) [기존 Starlight 프로젝트에 Tailwind를 추가할 때](#기존-프로젝트에-tailwind-추가하기), Starlight는 `src/styles/global.css` 파일에 있는 [Tailwind 테마 구성](https://tailwindcss.com/docs/theme)의 값을 사용하여 UI의 스타일을 지정합니다.

설정되면 다음 CSS 사용자 정의 속성이 Starlight의 기본 스타일을 재정의합니다.

- `--color-accent-*` — 링크 및 현재 항목 강조 표시에 사용됩니다.
- `--color-gray-*` — 배경색 및 테두리에 사용됩니다.
- `--font-sans` — UI 및 콘텐츠 텍스트에 사용됩니다.
- `--font-mono` — 코드 예시에 사용됩니다.

```css {9,11,13,25}
/* src/styles/global.css */
@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
	/* 선호하는 텍스트 글꼴입니다. Starlight는 기본적으로 시스템 글꼴 스택을 사용합니다. */
	--font-sans: 'Atkinson Hyperlegible';
	/* 선호하는 코드 글꼴입니다. Starlight는 기본적으로 시스템 고정폭 글꼴을 사용합니다. */
	--font-mono: 'IBM Plex Mono';
	/* 선호하는 강조 색상입니다. 남색(indigo)이 Starlight의 기본값과 가장 유사합니다. */
	--color-accent-50: var(--color-indigo-50);
	--color-accent-100: var(--color-indigo-100);
	--color-accent-200: var(--color-indigo-200);
	--color-accent-300: var(--color-indigo-300);
	--color-accent-400: var(--color-indigo-400);
	--color-accent-500: var(--color-indigo-500);
	--color-accent-600: var(--color-indigo-600);
	--color-accent-700: var(--color-indigo-700);
	--color-accent-800: var(--color-indigo-800);
	--color-accent-900: var(--color-indigo-900);
	--color-accent-950: var(--color-indigo-950);
	/* 선호하는 회색조입니다. 아연색(zinc)이 Starlight의 기본값과 가장 유사합니다. */
	--color-gray-50: var(--color-zinc-50);
	--color-gray-100: var(--color-zinc-100);
	--color-gray-200: var(--color-zinc-200);
	--color-gray-300: var(--color-zinc-300);
	--color-gray-400: var(--color-zinc-400);
	--color-gray-500: var(--color-zinc-500);
	--color-gray-600: var(--color-zinc-600);
	--color-gray-700: var(--color-zinc-700);
	--color-gray-800: var(--color-zinc-800);
	--color-gray-900: var(--color-zinc-900);
	--color-gray-950: var(--color-zinc-950);
}
```

### 여러 Tailwind 구성 사용하기

[하위 경로에서 Starlight를 사용](/ko/manual-setup/#하위-경로에서-starlight-사용)하거나 사이트에 [사용자 정의 페이지](/ko/guides/pages/#사용자-정의-페이지)를 추가할 때와 같이 사이트의 여러 부분에 서로 다른 스타일을 적용하기 위해 여러 Tailwind 구성을 사용할 수 있습니다.
예를 들어 사용자 정의 페이지에 Tailwind의 Preflight 재설정 스타일을 사용하면서 Starlight 페이지에는 Starlight의 호환성 레이어를 적용하고 싶을 수 있습니다.

다음 Tailwind CSS 구성은 플러그인이나 추가 구성 없이 Tailwind를 설정하며, Starlight가 아닌 페이지의 시작점으로 사용할 수 있습니다.

```css title="src/styles/custom-pages-tailwind.css"
/* Starlight의 보완 CSS 없이 Tailwind를 로드합니다. */
@import 'tailwindcss';
```

<Steps>

1. Starlight 페이지의 경우 ["기존 프로젝트에 Tailwind 추가하기"](#기존-프로젝트에-tailwind-추가하기)에 따라 원하는 Tailwind CSS 구성을 적용합니다.

2. 다른 페이지의 경우 해당 페이지에서 원하는 Tailwind CSS 구성을 가져와서 적용하세요. 이 작업은 레이아웃 컴포넌트에서 수행되는 경우가 많으므로 해당 레이아웃을 공유하는 모든 페이지에서 Tailwind 스타일을 사용할 수 있습니다.
   ```astro
   ---
   // src/layouts/CustomPageLayout.astro
   import '../styles/custom-pages-tailwind.css';
   ---
   ```

</Steps>

Tailwind 테마 구성에 대해 자세히 알아보려면 [Tailwind CSS 문서](https://tailwindcss.com/docs/theme)를 확인하세요.

## 테마

기본 사용자 정의 속성을 변경하여 Starlight의 색상 테마를 제어할 수 있습니다.
이러한 변수는 텍스트 및 배경색에 사용되는 다양한 회색 음영과 링크에 사용되는 강조 색상 및 탐색에서 현재 항목을 강조 표시하는 UI 전체에서 사용됩니다.

### 색상 테마 편집기

아래 슬라이더를 사용하여 Starlight의 강조 및 회색 색상 팔레트를 수정하세요. 어둡고 밝은 미리보기 영역에는 결과 색상이 표시되며 전체 페이지도 업데이트되어 변경 사항을 미리 확인할 수 있습니다.

대비 수준 옵션을 사용하여 웹 콘텐츠 접근성 가이드라인 [색상 대비 표준](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) 중 어느 것을 충족할지 지정합니다.

변경 사항이 만족스러우면 아래 CSS 또는 Tailwind 코드를 복사하여 프로젝트에 사용하세요.

import ThemeDesigner from '~/components/theme-designer.astro';

<ThemeDesigner
	labels={{
		presets: {
			label: '프리셋',
			ocean: '오션',
			forest: '숲',
			oxide: '옥사이드',
			nebula: '성운',
			default: '기본값',
			random: '무작위',
		},
		contrast: {
			label: '대비 수준',
		},
		editor: {
			accentColor: '강조',
			grayColor: '회색조',
			hue: '색상',
			chroma: '채도',
			pickColor: '색상 선택',
		},
		preview: {
			darkMode: '어두운 테마',
			lightMode: '밝은 테마',
			bodyText: '본문 텍스트는 배경과 대비가 높은 회색 음영으로 표시됩니다.',
			linkText: '링크에 색상이 지정됩니다.',
			dimText: '콘텐츠 목차와 같은 일부 텍스트는 대비가 낮습니다.',
			inlineCode: '인라인 코드에는 뚜렷한 배경이 있습니다.',
		},
	}}
>
	<Fragment slot="css-docs">
		[사용자 정의 CSS파일](#사용자-정의-css-스타일)에 아래 코드를 추가하여 현재 테마를 프로젝트에 적용하세요.
	</Fragment>
	<Fragment slot="tailwind-docs">
		사이트에 이 테마를 적용하려면 [Tailwind CSS 파일](#tailwind로-starlight-스타일링하기)의 `@theme` 블록에 다음 CSS 변수를 추가하세요.
	</Fragment>

</ThemeDesigner>
